Carapace For OpenClaw

The openclaw Security Advisor for OpenClaw gateways.

Built by CoChat.

Run one command. See exactly what's wrong with your gateway and how to fix it.

$ openclaw-carapace audit

  🦞 ┌─────────────────────┐ 🦞
  🦞 │   O P E N C L A W   │ 🦞
  🦞 │   C A R A P A C E   │ 🦞
  🦞 └─────────────────────┘ 🦞

   Config:  /Users/dev/.openclaw/openclaw.json
   Rules:   106 evaluated

   ─────────────────────────────────────────────

   Grade D  30/100  [██████░░░░░░░░░░░░░░]

   🦞 Walking around without a shell. Fix this.

   8 findings (4 critical)
   ↑ 55 pts recoverable via auto-fix

   ─────────────────────────────────────────────

   CRITICAL (4)

   ▸ Gateway authentication disabled                      -25pts
     No authentication is configured on the gateway.
     → Set gateway.auth.mode to 'token' with a strong random token.

   ▸ Sandboxing disabled — exec runs on host              -25pts  ✓ fixable
     Sandbox mode is 'off' and exec tools are not denied.
     → Set agents.defaults.sandbox.mode to 'non-main'.

   ▸ Gateway tool not denied — agent can modify config    -25pts  ✓ fixable
     A prompt injection can undo ALL security hardening.
     → Add 'gateway' to tools.deny.

   ▸ Elevated mode enabled                                -25pts  ✓ fixable
     Elevated exec bypasses sandboxing and runs on host.
     → Set tools.elevated.enabled to false.

   HIGH (2)

   ▸ Filesystem not restricted to workspace               -10pts  ✓ fixable
     Filesystem tools can access ~/.openclaw/ and credentials.
     → Set tools.fs.workspaceOnly to true.

   ▸ Tool loop detection disabled                         -10pts  ✓ fixable
     A stuck agent can execute the same tool call repeatedly.
     → Set tools.loopDetection.enabled to true.

   MEDIUM (2)

   ▸ Auth credential is short (< 32 chars)                -5pts
     Short credentials are easier to brute-force.
     → Use a random token of at least 32 characters.

   ▸ mDNS full mode — broadcasting sensitive info         -5pts   ✓ fixable
     Broadcasts install paths and SSH availability on LAN.
     → Set discovery.mdns.mode to 'minimal' or 'off'.

   ─────────────────────────────────────────────

   Run with --format json for machine-readable output
   Run with --format sarif for GitHub Code Scanning

Carapace tells you what's wrong, why it matters, and exactly what to change. Most findings can be auto-fixed.

📦 Install

npm install -g @cochatai/openclaw-carapace

Requires Node.js 18+. That's it.

🔍 What It Checks

Your config -- 24 rules catch misconfigurations in authentication, sandboxing, tool permissions, exec approvals, filesystem restrictions, DM policies, and more. Each finding explains the risk and tells you the fix.

Known vulnerabilities -- Carapace fetches 80+ CVEs and advisories from jgamblin/OpenClawCVEs (updated hourly) and checks them against your gateway version. Works offline too.

Third-party skills -- Scan any skill directory for hardcoded secrets, shell execution, network exfiltration, obfuscation, and known-malicious authors.

🚀 Usage

# Audit your gateway (auto-discovers ~/.openclaw/openclaw.json)
openclaw-carapace audit

# Point to a specific config
openclaw-carapace audit --config ./openclaw.json

# Scan a skill before installing it
openclaw-carapace skill scan ./some-skill/ --author "skill-author"

# See what hardening profiles are available
openclaw-carapace profiles list

# Output SARIF for GitHub Code Scanning
openclaw-carapace audit --format sarif > results.sarif

📊 Scoring

Your gateway gets a score out of 100. Findings deduct points based on severity:

Severity	Points	Example
Critical	-25	No authentication, sandboxing off
High	-10	No exec approval, filesystem unrestricted
Medium	-5	Log redaction off, short auth token
Low	-2	Web fetch enabled

Grades: A (90+), B (75-89), C (50-74), D (25-49), F (below 25)

One critical finding drops you from A to B. The score makes risk visible at a glance.

🤝 Contributing

We'd love your help. Whether it's a new audit rule, a better description for an existing finding, a blocklist update, or a bug fix -- contributions of any size are welcome.

git clone https://github.com/cochatai/openclaw-carapace.git
cd openclaw-carapace
npm install
npm run build
node dist/cli.js audit --help

Ways to contribute:

Report a security misconfiguration we're not catching -- open an issue
Add a new audit rule -- just create a YAML file in rules/ (see Writing Custom Rules below)
Report a malicious skill or author -- add to skills/blocklist/
Improve finding descriptions -- clarity helps everyone
Add tests, fix bugs, improve docs

📖 Reference

Everything below is detailed reference material. You don't need to read it to use Carapace -- the output tells you what to do. But it's here when you need it.

⌨️ CLI Reference

`audit`

openclaw-carapace audit [options]

Option	Description	Default
`-c, --config <path>`	Path to `openclaw.json`	Auto-discover
`-f, --format <fmt>`	Output: `text`, `json`, `sarif`	`text`
`-s, --min-severity <sev>`	Filter: `critical`, `high`, `medium`, `low`	`low`
`--rules-dir <path>`	Custom rules directory	Built-in
`--no-vulns`	Skip CVE/vulnerability checks
`--offline`	Don't fetch live advisories (use cache/static)

`skill scan`

openclaw-carapace skill scan <path> [options]

Option	Description	Default
`-f, --format <fmt>`	Output: `text`, `json`	`text`
`--author <author>`	Skill author (for blocklist check)
`--name <name>`	Skill name (for blocklist check)

`skill blocklist`

openclaw-carapace skill blocklist [--format text|json]

`profiles list` / `profiles show <id>`

openclaw-carapace profiles list
openclaw-carapace profiles show locked_down --format json

`patterns`

openclaw-carapace patterns [--format text|json]

`rules`

openclaw-carapace rules [--format text|json] [--offline]

Exit Codes

Code	Meaning
`0`	Clean -- no high or critical findings
`1`	High severity finding detected
`2`	Critical severity finding detected
`3`	Skill matches the blocklist

🛡️ Config Audit Rules

24 rules organized by severity. Rules with a CWE mapping indicate which vulnerability class they mitigate.

Critical (8 rules)

Rule ID	Title	CWE	Auto-fix
`gateway.no_auth`	Gateway authentication disabled	CWE-306
`gateway.bind_no_auth`	Gateway exposed without authentication	CWE-306
`dm_policy_open`	Open DM policy -- anyone can message the bot	CWE-306, CWE-345, CWE-285, CWE-863	Y
`tools.profile_full`	All tools unrestricted	CWE-78, CWE-22, CWE-918	Y
`elevated.enabled`	Elevated mode enabled	CWE-78, CWE-250, CWE-269	Y
`sandbox.mode_off`	Sandboxing disabled -- exec runs on host	CWE-78, CWE-250	Y
`tools.gateway_tool_enabled`	Gateway tool not denied -- agent can modify config	CWE-918, CWE-284	Y
`dangerous_flags`	Dangerous flag enabled		Y

High (7 rules)

Rule ID	Title	CWE	Auto-fix
`exec.host_sandbox_no_sandbox`	exec.host='sandbox' but sandbox is off	CWE-78, CWE-250	Y
`firewall.inactive`	Tool Firewall inactive	CWE-78, CWE-284	Y
`fs.not_workspace_only`	Filesystem tools not restricted to workspace	CWE-22, CWE-200	Y
`exec.security_full`	Exec runs all commands without approval	CWE-78, CWE-77	Y
`channels.open_groups_with_tools`	Open groups with runtime tools enabled
`tools.no_loop_detection`	Tool loop detection disabled		Y
`tools.cron_tool_enabled`	Cron tool available -- persistent scheduled jobs		Y

Medium (8 rules)

Rule ID	Title	Auto-fix
`config_includes_present`	Config includes detected
`custom_provider_external`	External model provider detected
`apply_patch.not_workspace_only`	apply_patch can write outside workspace	Y
`browser.enabled_no_sandbox`	Browser control enabled without sandboxing	Y
`auth.token_short`	Gateway auth credential is short (< 32 chars)
`plugins.no_allowlist`	Plugins without explicit allowlist
`logging.redact_off`	Log redaction disabled	Y
`discovery.mdns_full`	mDNS full mode -- broadcasting sensitive info	Y

Low (1 rule)

Rule ID	Title
`tools.web_fetch_enabled`	Web fetch/search tools enabled

🐛 Vulnerability Scanning

Carapace fetches live advisory data from jgamblin/OpenClawCVEs, a community-maintained repository updated hourly via GitHub Actions. This currently tracks 80+ advisories with GHSA IDs, CVE IDs, CVSS scores, affected version ranges, and fixed versions.

Each advisory becomes a version check that fires when your gateway.version is below the fix version. Carapace catches new vulnerabilities automatically as they're disclosed.

Postinstall fetch: When you npm install, Carapace automatically fetches the latest advisory data so the first audit run has CVE coverage immediately.

Cache: Advisory data is cached to ~/.openclaw-carapace/cache/ for 1 hour. Subsequent runs within that window don't hit the network.

Offline mode: --offline skips network fetches and uses cached data. If no cache exists, Carapace will warn you and skip vulnerability checks.

🔒 Hardening Profiles

Pre-built configuration patches that fix multiple findings at once.

Profile	Description
`locked_down`	Maximum security. Denies all runtime, filesystem, and control-plane tools. Forces sandboxing for all sessions. For messaging-only bots exposed to untrusted users.
`coding_safe`	Balanced security for coding agents. Keeps exec and filesystem tools but restricts them to the workspace. Denies control-plane tools. Enables exec approvals.
`messaging_safe`	Messaging tools only. Denies all runtime, filesystem, and automation tools.
`dm_hardened`	Locks all channel DM policies to `pairing` and isolates sessions per channel+peer. Does not change tool settings.

Use openclaw-carapace profiles show <id> --format json to see the exact config patch.

🧱 Exec Firewall Patterns

Carapace ships pattern definitions used by CoChat's runtime exec firewall. The CLI doesn't run a firewall itself — it just lets you inspect the bundled patterns via openclaw-carapace patterns.

Dangerous (auto-deny, 20 patterns) -- Destructive file ops (rm -rf /), credential theft (cat ~/.ssh/), remote code exec (curl | sh), system modification (chmod 777), network recon (nmap).

Suspicious (flag for review, 13 patterns) -- HTTP requests (curl, wget), package installation (pip install, npm install -g), privilege escalation (sudo), container operations (docker), environment access (printenv, history).

These patterns are safety rails, not security boundaries — regex-based interception can be bypassed by a determined adversary.

🕵️ Skill Scanning

Static Analysis (6 rule categories)

Rule	What it detects	CWE
`skill.hardcoded_secrets`	API keys, tokens, credentials in source code	CWE-798
`skill.command_execution`	Shell exec, eval, subprocess, child_process	CWE-78
`skill.network_exfiltration`	fetch, axios, http.request, WebSocket, etc.	CWE-200
`skill.filesystem_access`	References to ~/.ssh, ~/.aws, /etc/passwd, etc.	CWE-22
`skill.obfuscation`	base64 decode, fromCharCode, hex escapes	CWE-506
`skill.suspicious_dependencies`	Typosquatted packages, postinstall scripts	CWE-1357

Blocklist

Known-malicious indicators from published security research:

ClawHavoc campaign -- 335+ malicious skills on ClawHub delivering Atomic macOS Stealer (AMOS).
Known malicious authors -- Aggregated from Snyk ToxicSkills (2025), Bitdefender AI supply-chain research (2026), and community reports.

Checks author name, skill name, file SHA-256 hashes, C2 IP addresses, and known malicious domains.

⚙️ SARIF / CI Integration

Carapace outputs OASIS SARIF 2.1.0 for GitHub Code Scanning, VS Code SARIF Viewer, and other tools.

GitHub Actions

name: OpenClaw Security Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Audit OpenClaw config
        run: npx @cochatai/openclaw-carapace audit --format sarif > openclaw-carapace.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: openclaw-carapace.sarif

💻 Programmatic Usage

import {
  loadRules,
  fetchAdvisoryRules,
  evaluateRules,
  buildAuditResult,
  readConfig,
  reportText,
} from "@cochatai/openclaw-carapace";

const { config, path } = readConfig("./openclaw.json");

const configRules = loadRules();
const vulnRules = await fetchAdvisoryRules();
const allRules = [...configRules, ...vulnRules];

const findings = evaluateRules(allRules, config);
const result = buildAuditResult(findings, allRules.length, path);

console.log(reportText(result));

Custom Check Hooks

import { registerCustomCheck } from "@cochatai/openclaw-carapace";

registerCustomCheck("my_org_policy", (config) => {
  const findings = [];
  if (!config.myOrg?.approvedProvider) {
    findings.push({
      id: "my_org.no_approved_provider",
      severity: "high",
      title: "Organization-approved provider not configured",
      description: "...",
      recommendation: "...",
      config_path: "myOrg.approvedProvider",
      auto_fixable: false,
      points: 10,
    });
  }
  return findings;
});

Skill Scanning API

import {
  scanSkill,
  loadSkillRules,
  loadSkillBlocklist,
  reportSkillScan,
} from "@cochatai/openclaw-carapace";

const result = scanSkill("./my-skill", loadSkillRules(), loadSkillBlocklist(), {
  author: "some-author",
  name: "my-skill",
});

console.log(reportSkillScan(result));

✏️ Writing Custom Rules

Rules are YAML files. Drop them in a directory, pass --rules-dir, and Carapace picks them up.

id: my_custom_rule
severity: high
title: "My custom security check"
description: "Checks that my-setting is properly configured."
recommendation: "Set my-setting to 'secure'."
config_path: my.setting
auto_fixable: true
fix:
  my:
    setting: secure
check:
  type: value_equals
  path: my.setting
  value: secure

Available Check Types

Type	Description
`value_equals`	Fires when config value != expected (or == with `invert: true`)
`value_in_set`	Fires when value not in allowed set
`value_not_in_list`	Fires when a value is absent from a config array
`truthy`	Fires when value is truthy (or falsy with `invert: true`)
`key_exists`	Fires when key exists (or doesn't with `invert: true`)
`string_length`	Fires when string length is outside `min`/`max` bounds
`string_match`	Fires when string matches (or doesn't) a regex pattern
`cross_field`	Fires when ALL conditions across multiple config paths are true
`iterate_map`	Iterates a config map, applying a sub-check to each entry
`scan_keys`	Scans config keys matching a regex pattern
`url_check`	Validates URLs in a config map against trusted domains
`version_compare`	Compares a semver string (`lt`, `le`, `eq`, `ge`, `gt`)
`custom`	Delegates to a registered TypeScript function

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github		.github
patterns		patterns
profiles		profiles
rules		rules
skills		skills
src		src
tests/fixtures		tests/fixtures
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Carapace For OpenClaw

📦 Install

🔍 What It Checks

🚀 Usage

📊 Scoring

🤝 Contributing

📖 Reference

⌨️ CLI Reference

audit

skill scan

skill blocklist

profiles list / profiles show <id>

patterns

rules

Exit Codes

🛡️ Config Audit Rules

Critical (8 rules)

High (7 rules)

Medium (8 rules)

Low (1 rule)

🐛 Vulnerability Scanning

🔒 Hardening Profiles

🧱 Exec Firewall Patterns

🕵️ Skill Scanning

Static Analysis (6 rule categories)

Blocklist

⚙️ SARIF / CI Integration

GitHub Actions

💻 Programmatic Usage

Custom Check Hooks

Skill Scanning API

✏️ Writing Custom Rules

Available Check Types

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`audit`

`skill scan`

`skill blocklist`

`profiles list` / `profiles show <id>`

`patterns`

`rules`

Packages